---
title: "Connecting to a TimescaleDB database"
sidebarTitle: "TimescaleDB"
description: "Power time-series applications with real-time change capture. Learn how to connect TimescaleDB to Sequin."
icon: "clock"
iconType: "solid"
---

import CreateSequinDbUser from '/snippets/create-sequin-db-user.mdx';

This guide provides step-by-step instructions to connect your [TimescaleDB](https://www.timescale.com/) database to Sequin. TimescaleDB is an open-source database built on Postgres that's optimized for time-series data.

## Setting up TimescaleDB

If you don't have a TimescaleDB instance yet, you can set one up using Docker:

```bash
docker run -d --name timescaledb -p 5432:5432 \
-e POSTGRES_PASSWORD=postgres \
timescale/timescaledb-ha:pg16
```

## Enable logical replication

To determine if logical replication is already enabled for your TimescaleDB instance, you can run the following SQL command:

```sql
show wal_level;
```

This command should return `logical`. If it doesn't, you'll need to enable it by setting `wal_level` to `logical`.

<Warning>Enabling replication requires a restart of your database.</Warning>

<Steps titleSize="h3">
  <Step title="Configure WAL level">
    Connect to your TimescaleDB container and edit the PostgreSQL configuration:

```bash
# Connect to the container
docker exec -it timescaledb bash

# Edit postgresql.conf
echo "wal_level = logical" >> /home/postgres/pgdata/data/postgresql.conf

# Exit the container
exit

# Restart the container for changes to take effect
docker restart timescaledb
```
  </Step>
</Steps>

<Tip>
  You can also find the location of your `postgresql.conf` file by running the SQL command `show config_file;`.
</Tip>

## Provision a Postgres user for Sequin
<CreateSequinDbUser />

## Connect Sequin to your TimescaleDB database

After enabling logical replication, you'll now connect to your database in Sequin:

<Steps titleSize="h3">
  <Step title="Enter connection details in Sequin">
    In the Sequin Console, click on the "Connect Database" button and enter the credentials for your TimescaleDB database:

    - Host: Your TimescaleDB host (e.g., `localhost` or your Docker machine IP)
    - Port: 5432 (default Postgres port)
    - Database: Your database name
    - Username: The sequin database user you created earlier
    - Password: The password for your sequin database user
  </Step>

  <Step title="Create a publication">
    Connect to your database using the SQL client of your choice and execute one of the following SQL queries to create a publication:

```sql
-- Option 1: Recommended approach - capture all tables
CREATE PUBLICATION sequin_pub FOR ALL TABLES;

-- Option 2: If you need to capture specific schemas (includes TimescaleDB internal tables)
CREATE PUBLICATION sequin_pub FOR TABLES IN SCHEMA public, _timescaledb_internal;
```

<Warning>
  When using TimescaleDB, there are important considerations for publications:

  1. Using `FOR ALL TABLES` is the most reliable approach, though it requires more resources
  2. If you need to publish specific tables, you must include both:
     - The schema containing your base tables (usually `public`)
     - The TimescaleDB internal schema (`_timescaledb_internal`)
  3. Avoid using `FOR TABLE table_name` with TimescaleDB hypertables, as this can cause replication to stop when new chunks are created
</Warning>

<Note>
  For either approach, you can further limit which tables are replicated with [table filtering in Sequin](/reference/sinks/overview#source-tables) instead.
</Note>

  </Step>

  <Step title="Create a replication slot">
    Next, create a replication slot to capture changes from the publication:

```sql
select pg_create_logical_replication_slot('sequin_slot', 'pgoutput');
```
  </Step>

  <Step title="Enter the replication slot details in Sequin">
    Back in the Sequin Console, enter the name of the replication slot (e.g. `sequin_slot`) and publication (e.g. `sequin_pub`) you just created. Then, name your database and click "Create Database".
  </Step>
</Steps>

## Create a sink

With your TimescaleDB database connected to Sequin, you are ready to create a sink. Follow one of our guides below to get started:

<CardGroup cols={2}>
  <Card
    title="Stream to Webhooks"
    icon="webhook"
    href="/how-to/stream-postgres-to-a-webhook-endpoint"
  >
    Send database changes to your HTTP endpoints to trigger workflows and keep services in sync
  </Card>
  <Card
    title="Stream to Redis Streams"
    icon="layer-group"
    href="/how-to/stream-postgres-to-redis-stream"
  >
    Stream changes to Redis Streams for real-time data processing and caching
  </Card>
  <Card
    title="Stream to Kafka"
    icon="code-branch"
    href="/how-to/stream-postgres-to-kafka"
  >
    Publish database changes to Kafka topics for event streaming and processing
  </Card>
  <Card
    title="Stream to SQS"
    icon="aws"
    href="/how-to/stream-postgres-to-sqs"
  >
    Send changes to AWS SQS queues to trigger Lambda functions and other AWS services
  </Card>
</CardGroup>